本文使用官方二进制在 Linux 上安装 Gitea Actions Runner,由 systemd 管理进程,默认通过 Docker 容器执行作业。适用于 AMD64 / ARM64 主机,示例固定使用 5.4.1,不自动追踪最新版本。
“物理机部署”指 Runner 进程直接运行在宿主机上;作业是否在宿主机执行,由 Runner 的标签决定。本文也适用于 Linux 虚拟机。
本文用于首次安装。已有 Runner 请参考 Gitea Action Runner 升级,不要直接覆盖现有配置或重复注册。旧教程中的
act_runner与本文的gitea-runner名称和命令可能不同,请以目标版本的帮助信息为准。
一、部署前准备
按 Runner 5.x 官方要求,部署前确认:
- Gitea 为 1.21 或更高版本,且已启用 Actions;需要运行工作流的仓库也应启用 Actions。
- Runner 主机已安装 Git 2.34.1 或更高版本,以及正在运行的 Docker Engine。
- Runner 主机与作业容器均能访问 Gitea 的对外地址;还需能下载作业镜像和工作流使用的 Action。
- 安装命令在 root 的 Bash 会话中执行;服务使用单独的
gitea-runner用户运行。
Debian / Ubuntu 可先安装基础工具,Docker 请按 Docker 官方安装文档单独安装:
sudo -i
apt-get update
apt-get install -y ca-certificates wget xz-utils coreutils git
# Git 版本必须满足要求
git --version
systemctl enable --now docker
docker info
其他发行版请使用对应的包管理器,后续命令仍在 root 的 Bash 会话中执行。
二、下载并校验 Runner
将以下内容保存为 install-gitea-runner.sh。脚本识别 CPU 架构,下载官方压缩包及 SHA256 文件,校验成功后才安装。
#!/usr/bin/env bash
set -euo pipefail
VERSION="5.4.1"
INSTALL_PATH="/usr/local/bin/gitea-runner"
if [[ $EUID -ne 0 ]]; then
echo '请使用 root 运行'
exit 1
fi
# 首次安装不覆盖已有程序;升级请使用升级流程。
if [[ -e "$INSTALL_PATH" ]]; then
echo "程序已存在:$INSTALL_PATH,请改用升级流程"
exit 1
fi
case "$(uname -m)" in
x86_64|amd64) ARCH="amd64" ;;
aarch64|arm64) ARCH="arm64" ;;
*) echo "不支持的架构:$(uname -m)"; exit 1 ;;
esac
BINARY_NAME="gitea-runner-${VERSION}-linux-${ARCH}"
DOWNLOAD_URL="https://dl.gitea.com/gitea-runner/${VERSION}/${BINARY_NAME}.xz"
TMP_DIR="$(mktemp -d)"
trap 'rm -rf -- "$TMP_DIR"' EXIT
cd "$TMP_DIR"
wget --https-only --tries=3 --timeout=30 -O "${BINARY_NAME}.xz" "$DOWNLOAD_URL"
wget --https-only --tries=3 --timeout=30 -O "${BINARY_NAME}.xz.sha256" "${DOWNLOAD_URL}.sha256"
sha256sum -c "${BINARY_NAME}.xz.sha256"
xz -d "${BINARY_NAME}.xz"
install -m 0755 "$BINARY_NAME" "$INSTALL_PATH"
"$INSTALL_PATH" --version
执行安装:
bash install-gitea-runner.sh
预期输出包含校验 OK 和 5.4.1 版本信息。下载失败时,先检查 5.4.1 官方文件目录中的文件名、架构和版本;校验失败不要继续安装。
三、创建运行用户与配置
将配置与运行数据分开存放,路径约定如下:
| 路径 | 用途 |
|---|---|
/usr/local/bin/gitea-runner |
可执行文件 |
/etc/gitea-runner/config.yaml |
Runner 配置 |
/var/lib/gitea-runner/ |
服务工作目录、用户主目录 |
/var/lib/gitea-runner/.runner |
注册信息,包含凭据 |
/etc/systemd/system/gitea-runner.service |
systemd 服务 |
首次安装时执行:
useradd --system --user-group --home-dir /var/lib/gitea-runner \
--create-home --shell /usr/sbin/nologin gitea-runner
usermod -aG docker gitea-runner
chmod 0700 /var/lib/gitea-runner
install -d -m 0750 -o root -g gitea-runner /etc/gitea-runner
# 生成当前版本的配置参考,不覆盖正式配置
gitea-runner config generate > /etc/gitea-runner/config.example.yaml
加入
docker组可以操作 Docker socket,实际上具有宿主机 root 级能力。请在专用 CI 主机上运行可信仓库的作业;使用专用用户并不代表 Docker 作业具有完整的安全隔离。
创建本文使用的最小配置:
cat > /etc/gitea-runner/config.yaml <<'EOF'
log:
level: info
runner:
file: /var/lib/gitea-runner/.runner
capacity: 1
timeout: 3h
shutdown_timeout: 30s
labels:
- "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
EOF
chown root:gitea-runner /etc/gitea-runner/config.yaml
chmod 0640 /etc/gitea-runner/config.yaml
# 确认服务用户可以访问 Docker
sudo -u gitea-runner -H docker info
其余选项使用 Runner 默认值;完整说明见生成的参考文件和配置文档。capacity: 1 表示同时执行一个作业。停止服务时,shutdown_timeout: 30s 允许正在执行的作业继续运行最多 30 秒,超时后取消。
标签与执行环境
本文的标签映射为:
ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest
└─ runs-on 名称 └─ 作业容器镜像
工作流写 runs-on: ubuntu-latest,作业就使用该镜像。它不会把宿主机变成 Ubuntu,也不要求宿主机必须是 Ubuntu。ARM64 主机需要确认所选镜像及工作流依赖支持 ARM64。
如果确实需要直接在宿主机执行作业,可将 runner.labels 改为 linux-host:host,工作流相应写 runs-on: linux-host。此时需要在宿主机准备 Bash、Git、Node.js 及构建工具,作业以服务用户身份执行,没有容器隔离。仅运行 host 作业且不使用 Docker Action 时可省略 Docker,并移除后文服务中的 Docker 依赖。
标签的详细规则见官方标签文档。修改配置后需要重启服务生效,不需要重新注册。
四、获取令牌并注册
在 Gitea 中按用途选择 Runner 范围:仓库、组织或整个实例。个人仓库优先使用仓库级 Runner,避免接受无关仓库的任务。
进入对应范围的 设置 → Actions → Runners 获取注册令牌;实例级入口位于站点管理中,具体位置随 Gitea 版本可能略有差异。这里需要的是 Runner 注册令牌,不是个人访问令牌(PAT)。参考 Gitea 的 Runner 管理说明。
在工作目录中,以服务用户交互式注册:
cd /var/lib/gitea-runner
sudo -u gitea-runner -H /usr/local/bin/gitea-runner \
--config /etc/gitea-runner/config.yaml register
按提示填写:
| 项目 | 示例或说明 |
|---|---|
| Gitea 地址 | https://gitea.example.com/,替换为实际实例的 ROOT_URL |
| 注册令牌 | 从对应范围的 Runner 设置页复制 |
| Runner 名称 | 如 linux-runner-01,便于区分主机 |
| 标签 | 本文已在配置中指定,通常不会再询问 |
不要使用 localhost 或 127.0.0.1 作为 Gitea 地址:它们在作业容器中指向容器自身。注册地址应能从宿主机和作业容器访问。
注册成功后检查文件权限,不要输出文件内容:
chmod 0600 /var/lib/gitea-runner/.runner
ls -l /var/lib/gitea-runner/.runner
.runner 保存身份凭据,应持久保存且不要提交到 Git。日常重启无需再次注册;注册文件丢失时才需要重新注册,并清理 Gitea 中失效的旧 Runner 记录。详见官方注册文档。
五、配置 systemd 服务
本文使用本机 Docker Engine,服务同时声明 Docker 启动顺序和依赖:
cat > /etc/systemd/system/gitea-runner.service <<'EOF'
[Unit]
Description=Gitea Actions Runner
Documentation=https://docs.gitea.com/runner/
Wants=network-online.target
After=network-online.target docker.service
Requires=docker.service
[Service]
Type=simple
User=gitea-runner
Group=gitea-runner
WorkingDirectory=/var/lib/gitea-runner
Environment=HOME=/var/lib/gitea-runner
ExecStart=/usr/local/bin/gitea-runner daemon --config /etc/gitea-runner/config.yaml
Restart=on-failure
RestartSec=10s
TimeoutStopSec=60s
UMask=0077
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now gitea-runner
systemctl status gitea-runner --no-pager
journalctl -u gitea-runner -n 50 --no-pager
TimeoutStopSec 大于配置中的 shutdown_timeout,为 Runner 退出预留时间。后续如延长作业等待时间,应同步调整两处数值。配置只在启动时读取,修改后执行 systemctl restart gitea-runner;这里不配置未经确认支持的 HUP 重载。
六、运行工作流验证
先在 Gitea 对应的 Runner 页面确认它已在线、标签包含 ubuntu-latest,再在测试仓库创建 .gitea/workflows/runner-check.yaml:
name: Runner Check
on: [push]
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: https://github.com/actions/checkout@v4
- name: Check environment
run: |
uname -m
git --version
node --version
git rev-parse --short HEAD
echo "Runner is ready"
提交并推送到测试仓库后,在 Actions 页面检查作业是否成功。首次执行需要下载镜像和 Checkout Action,因此主机需要相应的网络访问能力;示例使用显式 GitHub 地址。
以下三项均通过,才能确认部署可用:
- systemd 服务处于
active。 - Gitea 页面中 Runner 在线且标签正确。
- 工作流能检出代码、执行命令,并回传日志及成功状态。
七、日常管理与排错
# 查看服务状态和实时日志
systemctl status gitea-runner --no-pager
journalctl -u gitea-runner -f
# 修改配置后重启;操作前确认没有正在执行的重要任务
systemctl restart gitea-runner
# 停止服务 / 取消开机启动
systemctl stop gitea-runner
systemctl disable gitea-runner
服务启动失败或 Runner 离线
systemctl cat gitea-runner
journalctl -u gitea-runner -n 100 --no-pager
sudo -u gitea-runner -H test -r /etc/gitea-runner/config.yaml
sudo -u gitea-runner -H test -r /var/lib/gitea-runner/.runner
sudo -u gitea-runner -H docker info
重点检查程序路径、YAML 缩进、注册文件是否属于服务用户、Docker 是否启动,以及主机到 Gitea 的 DNS、网络与 TLS 证书。test -r 成功时没有输出,失败时返回非零状态。
若使用私有 CA,需要同时解决宿主机和作业镜像的证书信任;不要把关闭 TLS 校验当作常规修复。systemd 服务也不会自动继承当前终端的代理变量,需要时在服务中单独设置环境变量,并区分 Runner、Docker daemon 和作业容器各自的代理配置。
作业一直等待
检查仓库是否启用 Actions、Runner 的注册范围是否覆盖该仓库、runs-on 是否匹配标签,以及唯一的并发槽位是否被其他任务占用。仅看到服务 active,不能证明 Runner 已成功连接 Gitea。
注册成功,但检出代码失败
注册只证明 Runner 进程能访问 Gitea;Checkout 在作业环境中执行。检查 Gitea 对外地址是否能从容器解析和访问,避免使用本机回环地址,同时核对容器的 CA 证书和网络设置。
拉取镜像失败或提示 exec format error
前者优先检查 Docker daemon 到镜像仓库的网络、认证与代理;后者检查 Runner 二进制、作业镜像和下载工具的 CPU 架构是否与主机一致。ARM64 主机不能仅因为标签叫 ubuntu-latest 就假定能运行只支持 AMD64 的工具。